<HTML>
<HEAD><TITLE>Terraform Users Guide</TITLE></HEAD>

<BODY BGCOLOR=#FFFFFF TEXT=#000000 LINK=#000000 ALINK=#000000 VLINK=#000000>
<H1>Terraform Users Guide</H1>

<I>Author: Robert Gasch</I>,
<I>Updated by David A. Bartold</I>
<I>Updated by Koos Jan Niesink</I>

<P>
This is the user's guide for terraform, an interactive digital terrain
generator/modeller.
</P>

<HR NOSHADE>

<H2>Table of Contents</H2>
<UL>
<LI><A HREF="#FAQ">FAQ (Frequently Asked Questions)</A>
<LI><A HREF="#Tutorial">Tutorial</A>
<LI><A HREF="#MainWindow">The Main Window</A>
    <UL>
    <LI><A HREF="#New">Generating a New Heightfield</A>
        <UL>
        <LI><A HREF="#PerlinNoise">Perlin Noise</A>
        <LI><A HREF="#Spectral">Spectral</A>
        <LI><A HREF="#Subdivision">Subdivision</A>
        <LI><A HREF="#Random">Random</A>
        </UL>
    <LI><A HREF="#Merge">Merging Two or More Terrains</A>
    <LI><A HREF="#MainOptions">The Global Options Dialog</A>
    </UL>
<LI><A HREF="#TerrainWindow">The Terrain Window</A>
    <UL>
    <LI><A HREF="#Views">Views</A>
    <LI><A HREF="#Rendering">Rendering</A>
        <UL>
        <LI><A HREF="#RenderOptions">The Render Options Dialog</A>
        <LI><A HREF="#POVRay">Rendering in POV-Ray</A>
        </UL>
    <LI><A HREF="#Basic">Basic Height Field Transforms</A>
        <UL>
        <LI><A HREF="#Invert">Invert</A>
        <LI><A HREF="#Mirror">Mirror</A>
        <LI><A HREF="#Move">Move</A>
        <LI><A HREF="#Rotate">Rotate</A>
        <LI><A HREF="#Scale">Scale</A>
        </UL>
    <LI><A HREF="#Specialized">Specialized Height Field Transforms</A>
        <UL>
        <LI><A HREF="#Connect">Connect</A>
        <LI><A HREF="#Craters">Craters</A>
        <LI><A HREF="#Erode">Erode</A>
        <LI><A HREF="#Fill">Fill</A>
        <LI><A HREF="#Flowmap">Flowmap</A>
        <LI><A HREF="#Fold">Fold</A>
        <LI><A HREF="#GaussianHill">Gaussian Hill</A>
        <LI><A HREF="#RadialScale">Radial Scale</A>
	<LI><A HREF="#Rasterize">Rasterize</A>
        <LI><A HREF="#Roughen">Roughen</A>
        <LI><A HREF="#Smooth">Smooth</A>
        <LI><A HREF="#Terrace">Terrace</A>
        <LI><A HREF="#Tile">Tile</A>
        <LI><A HREF="#Transform">Transform</A>
        </UL>
    <LI><A HREF="#Objects">Objects</A>
        <UL>
	<LI><A HREF="#Show">Show</A>
        <LI><A HREF="#Place">Place</A>
        <LI><A HREF="#RemoveAll">Remove All</A>
        <LI><A HREF="#MoveObjects">Move</A>
        </UL>
    <LI><A HREF="#Advanced">Advanced Topics</A>
        <UL>
	<LI><A HREF="#Adding_Files">Adding your own scene files and objects</A>
        <LI><A HREF="#Hacking">Hacking Terraform</A>
        <LI><A HREF="#Templates">Writing POV-Ray Templates</A>
        </UL>
    </UL>
</UL>

<A NAME="FAQ">
<H2>FAQ (Frequently Asked Questions)</H2>
<P>
Answers to many common questions are available <A HREF="faq.html">here</A>.
</P>

<A NAME="Tutorial">
<H2>Tutorial</H2>
<P>
A quick tutorial is available <A HREF="tutorial.html">here</A> for first
time users.
</P>

<A NAME="MainWindow">
<H2>Main Window</H2>
<P>
The main window allows the user to open new terrain windows.  A terrain
can be loaded or created using one of several algorithms.  The Options
window accessable from the main window menu exposes several
global parameters such as the POV-Ray executable location and
maximum undo size.
</P>

<A NAME="New">
<H3>Generating a New Heightfield</H3>
<P>
The easiest way to generate a new terrain is to select the "Random" menu
item.  It will automatically select one of several different algorithms using
randomly generated parameters and create a new heightfield for you.
</P>

<A NAME="PerlinNoise">
<H4>Perlin Noise</H4>
<P>
The Perlin layered noise function is calculated by taking the sum of
several octaves of noise.  To produce a two dimensional octave of noise,
a grid of random numbers are interpolated.  The distance between the
points is determined by the frequency.
</P>

<A NAME="Spectral">
<H4>Spectral Synthesis</H4>
<P>
Spectral synthesis involves filling an array with random data.  The
array is fed to an inverse fourier function to generate terrain.
</P>

<A NAME="Subdivision">
<H4>Subdivision</H4>
<P>
The subdivision algorithms initially set several outer points to
random values and those points are used to calculate an interior
point.  For example, the recursive square algorithm sets the
four corners of the terrain to random values.  The center point's value is
calculated by averaging the value of the four corners and adding a
random number.  The random number is multiplied by the size of the square
so that larger distances have greater variation.  Finally the
algorithm divides the square into quarters and recurses on each.
</P>

<A NAME="Random">
<H4>Random</H4>
<P>
Generates a new terrain using a randomly chosen algorithm.  The terrain
size will be 400 x 400 pixels.
</P>

<A NAME="Merge">
<H3>Merging Two or More Terrains</H3>
<P>
<I>Multiplies two terrains by different coefficients and combines them using
an operator such as addition.  Merged terrains are automatically normalized--
their height is stretched such that the lowest point's value is 0.0 and the
highest point is 1.0.
</I>

<A NAME="MainOptions">
<H3>The Global Options Dialog</H3>
<P>
<I>Provides application-wide settings such as the POV-Ray executable name,
maximum undo levels, and gamma.</I>

<A Name="TerrainWindow">
<H2>The Terrain Window</H2>
<P>
<I>[To be written]</I>
</P>

<A NAME="Views">
<H3>Views</H3>
<P>
<I>[To be written]</I>
</P>

<A NAME="Rendering">
<H3>Rendering</H3>
<P>
<I>[To be written]</I>
</P>

<A NAME="RenderOptions">
<H3>The Render Options Dialog</H3>
<P>
<I>[To be written]</I>
</P>

<A NAME="POVRay">
<H3>Rendering in POV-Ray</H3>
<P>
<I>Exports the terrain to POV-Ray and calls the povray executable specified
in the main options window.  POV-Ray must be able to find its include files.
Make sure you have a .povrayrc file in your home directory that has
a line such as Library_Path=/usr/share/povray31/include.</I>
</P>

<A NAME="Basic">
<H3>Basic Height Field Transforms</H3>
<P>
<I>This menu provides essential operations you'd expect in a terrain
manipulation program</I>
</P>

<A NAME="Invert">
<H4>Invert</H4>
<P>
Inverts the current height field, leaves the waterlevel unchanged.
</P>

<A NAME="Mirror">
<H4>Mirror</H4>
<P>
Mirror the height field along one of four axis. Horizontal (-),
vertical (|), top-left bottom-right (\) or bottom-left top-right (/).
This is useful for leaving the general characteristics of the
landscape intact while changing it's layout.
</P>

<A NAME="Move">
<H4>Move</H4>
<P>
Offset the terrain wrapping it around the edges.  Useful for moving
a mountain to a desired location.  If the terrain was not generated
using spectral synthesis, it may be desirable to run the Tile filter first.
</P>

<A NAME="Rotate">
<H4>Rotate</H4>
<P>
Rotate the height field in increments of 90 degrees.
</P>

<A NAME="Scale">
<H4>Scale</H4>
<P>
Allows you to either double or half the size of the current height
field.  A fractal algorithm is used to double the size of a terrain.
</P>

<A NAME="Specialized">
<H3>Specialized Height Field Transforms</H3>
<P>
<I>These operations map specific features onto a terrain.</I>
</P>

<A NAME="Connect">
<H4>Connect</H4>
<P>
This is the level connector plug-in as used in the MS Windows terrain
editor leveller.  It smooths selected terrain.
</P>

<A NAME="Craters">
<H4>Craters</H4>
<P>
Place the specified number of craters on the height field using the
specified parameters. This is a slightly modified version of John
Beale's hf-lab crater routines. On the crater dialog, if you reduce
the number of craters to 1, you can specify the exact locaton of the
crater.  Craters are placed only in selected areas.  A crater is fully
rendered even if it overlaps a nonselected area.
</P>

<A NAME="Erode">
<H4>Erode</H4>
<P>
This routine calculates the flowmap and the uses the flowmap to erode
the terrain, refreshing the flowmap at regular intervals (thus trading
accuracy for speed). This is a lot faster than John Beale's code, but
needs some more work.
</P>

<A NAME="Fill">
<H4>Fill</H4>
<P>
Fill the terrain object up to the specified elevation, using using the
tightness parameter to determine how much the altered points are
allowed to deviate from the specified elevation.
</P>

<A NAME="Flowmap">
<H4>Flowmap</H4>
<P>
Calculate the flowmap of the current height field (see code for
details). You can choose between the Single-Flow-Direction algorithm
(which is reasonably fast) or the Multiple-Flow-Direction algorithm
(which is slow). On my machine (AMD K6-233) SFD takes
about 2.5 seconds, while MFD takes around 30 minutes for a 400x400
height field.
</P>

<A NAME="Fold">
<H4>Fold</H4>
<P>
The 'fold' option allows you to create a margin at the edge of the
height field which is submerged below the current sealevel. This is
useful to force a generated height field to be integratable into a
scene with a predictable horizon or sealevel and is probably best used
in small multiple steps.
</P>

<A NAME="GaussianHill">
<H4>Gaussian Hill</H4>
<P>
This creates a gaussian hill at the specified location with the
specified parameters. You can use the 1st and 2nd mouse button to set
the location parameters.
</P>

<A NAME="RadialScale">
<H4>Radial Scale</H4>
<P>
Picks a point and scales the surrounding terrain in a circular maner.
Can be used to make all sorts of circular shapes. Still needs some
work.
</P>

<A NAME="Rasterize">
<H4>Rasterize</H4>
<P>
This filter equalizes the elevation in the terrain in small rectangular 
sections. The tightness factor determines the "blockyness" of the terrain.
</P>

<A NAME="Roughen">
<A NAME="Smooth">
<H4>Roughen and Smooth</H4>
<P>
   Use neighbour-averaging to roughen or smooth the height field. The
   factor determines how much of the computed roughening is actually
   applied to the height field. In it's default invocation, the 4
   directly neighbouring squares are used to calculate the roughening. If
   you select big sampling grid, all 8 neighbouring cells will be used.
</P>

<A NAME="Terrace">
<H4>Terrace</H4>
<P>
Divide the terrain object into n specified levels with the specified
closeness factor.
</P>

<A NAME="Tile">
<H4>Tile</H4>
<P>
Make the current height field tilable. Still needs some work.
</P>

<A NAME="Transform">
<H4>Transform</H4>
<P>
Transform applies power transformations to the current height field
such that the land's height becomes statistically similar to the earth.
Edges around the land flatten and drop sharply to the smooth ocean floor.
</P>

<A NAME="Objects">
<H3>Objects</H3>
<P>
</P>

<A NAME="Show">
<H4>Show</H4>
<P>
This show the <a href="show_objects.html">standard objects</a> available in Terraform.
</P>

<A NAME="Place">
<H4>Place</H4>
<P>
Place objects of one particular type onto a terrain
</P>

<A NAME="RemoveAll">
<H4>Remove All</H4>
<P>
Removes all objects from the terrain.
</P>

<A NAME="MoveObjects">
<H4>Move</H4>
<P>
Go into 2D Plane mode.  Select the pointer toolbar button and move objects
around by dragging and dropping them.
</P>

<A NAME="Advanced">
<H3>Advanced Topics</H3>
<P>
<I>[To be written]</I>
</P>

<A NAME="Adding_Files">
<H4>Adding your own scene files and objects</H4>
<P>
It is possible to add your own scenes and objects to terraform. Go to the 
~/.terraform directory and create the subfolders "objects", "themes" and "includes". 
Now you can place the files in the corresponding directory, now they can be used 
by terraform. If files with the same name occur in your home directory and in the 
system terraform directory the files in the home directory are used for rendering.
</P>

<A NAME="Hacking">
<H4>Hacking Terraform</H4>
<P>
See the <A HREF="hacking.html">Hacking Terraform</A> document for more information.
</P>

<A NAME="Templates">
<H4>Writing POV-Ray Templates</H4>
<P>
See the <A HREF="templates.html">Writing POV-Ray Templates</A> document for more information.
</P>

</BODY>
</HTML>
